home *** CD-ROM | disk | FTP | other *** search
/ QuickTime 2.0 Developer Kit / QuickTime 2.0 Developer Kit.iso / mac / MAC / Programming Stuff / Sample Code / Video Digitizer / Easy Video Grabber / README < prev    next >
Encoding:
Text File  |  1994-12-06  |  6.9 KB  |  191 lines  |  [TEXT/MPS ]
  1. README: Easy Video Grabber
  2.  
  3. VERSION (Date)
  4. 12-06-94
  5.  
  6. GENERAL
  7. This example  is a simple example of a wrapper library around the video digitizer functions.
  8. See discussion at the end of this document for more details.
  9.  
  10.  
  11.  
  12. ENVIRONMENT USED
  13. Metrowerks 4.5
  14. Think 7.0.3
  15. QT 2.0
  16. Universal Headers (ETO#16)
  17. System 7.5
  18.  
  19.  
  20. HOW TO BUILD
  21. Select either the Think or the Metrowerks project file if
  22. you want to rebuild the samples.
  23.  
  24.  
  25. HOW TO TEST
  26. Run the application.
  27.  
  28.  
  29. ERROR REPORTS
  30. If you encounter problems with this sample, send a report stating:
  31.  
  32.  
  33. * Name of the sample (and the source code file)
  34. * How the error is reproduced
  35. * What source code lines in the sample are problematic
  36. * What version of the sample you have, or from what source did you obtain the sample
  37. * Your environment, specifying:
  38.     - System environment (System 7.0, 7.1, 7.5 and so on)
  39.     - QuickTime environment (QT 1.6.1, 2.0 and so on)
  40.     - Any additional extensions in your system
  41.     - Hardware environment
  42.     - Development environment (including version level)
  43. * Any other valuable feedback and comments
  44.     
  45. Send this report to APPLE.BUGS on AppleLink, or APPLE.BUGS@applelink.apple.com 
  46. on Internet. If possible use the bug reporter stack that is available on
  47. the  Developer CDs, AppleLink and ftp.apple.com.
  48.  
  49.  
  50. LEGAL STATEMENTS
  51. Copyright © 1992-94 Apple Computer, Inc.
  52. All rights reserved.
  53.  
  54. You may incorporate this sample code into your applications without
  55. restriction, though the sample code has been provided "AS IS" and the
  56. responsibility for its operation is 100% yours.  However, what you are
  57. not permitted to do is to redistribute the source as "DSC Sample Code"
  58. after having made changes. If you're going to re-distribute the source,
  59. we require that you make it clear in the source that the code was
  60. descended from Apple Sample Code, but that you've made changes.
  61.  
  62.  
  63.  
  64. CHANGE HISTORY
  65. 12/06/94    khs        Tested with MW 4.5, Think C 7.0.3 and ETO#16 Universal headers.
  66.  
  67.  
  68. MORE INFORMATION
  69.  
  70. How To Capture A Video Frame
  71. ___________________________________________________
  72. by David Van Brink
  73.  
  74.  
  75.     One of the design goals of all Macintosh System Software is to provide 
  76.     "plug-and-play" hardware installation. For example, to install a screen 
  77.     on your Macintosh, you simply plug in the Nubus board, wire it to your monitor, 
  78.     and boot up the computer. QuickTime adds this "plug-and-play" simplicity for 
  79.     video digitizers, which convert a video image (such as from a VCR or video camera) 
  80.     into some machine readable form (such as a PICT). Why would you want to digitize 
  81.     a video image? For all the same reasons that you would want to scan an image 
  82.     with a scanner; the main difference is that the type of importable imagery 
  83.     is not bits of paper, but anything that exists as video.
  84.  
  85.     Recently, I was writing a small application that required the use of a video 
  86.     digitizer card. This application required only the very simplest of digitizing 
  87.     operations: “Capture a single frame, now, please.” QuickTime defines a standard 
  88.     interface for video digitizing cards; however, this interface is very complex, 
  89.     and allows each digitizer card considerable flexibility as to which features are 
  90.     or aren’t implemented. QuickTime therefore provides a component called the 
  91.     “Sequence Grab” component, which  simplifies the interface to  video digitizers, 
  92.     by handling offscreen buffering, and scaling, and a myriad other details. But, 
  93.     the “Sequence Grab” component was still too complex for my tastes, and didn’t 
  94.     have my desired “Capture a single frame, now, please” command.
  95.  
  96.     So, after much gnashing of teeth and keyboard, I came up with a very tiny 
  97.     little library of routines that simply grabs a single frame of video into the current 
  98.     GrafPort, into a requested rectangle. This library should be helpful to you, 
  99.     the Macintosh programmer with an interest in QuickTime and video, in two ways. 
  100.     One: you may be able to use it just as it is for some simple applications. 
  101.     Two: you can follow the easy-to-read source code and see exactly what are the 
  102.     minimal steps necessary to grab a video frame, using the “Sequence Grab” component.
  103.  
  104.     Two files are needed: “BigEasyVideoGrabber.h” and “BigEasyVideoGrabber.c.” You’ll 
  105.     need to include the ‘.h file in your sources to use these routines. You’ll 
  106.     need to compile and link your code with the ‘.c file.
  107.  
  108. Descriptions of the three easy routines follow.
  109.  
  110.  
  111. Three Easy Routines
  112.  
  113. EasyVideoGrabber NewEasyVideoGrabber(Rect *outputSize);
  114.  
  115.     This routine locates a video digitizer card, and initializes it, and returns a pointer 
  116.     to a structure called an “EasyVideoGrabber,” which you’ll pass to the other two routines 
  117.     in the library. If there is more than one digitizer in the Macintosh, then you cannot 
  118.     specify which is used.
  119.     The rectangle, “outputSize,” is filled in with the bounds of the video frame that 
  120.     the digitizer can return. For example, a full-resolution digitizer might return the 
  121.     rectangle (0,0,640,480), while a low-resolution device might only be (0,0,160,120).
  122.     If “nil” is returned, there was some problem with using a video digitizer. A common 
  123.     reason for a “nil” return is that the Macintosh has no video digitizer.
  124.  
  125. Boolean GrabEasyVideoGrabber(EasyVideoGrabber evg,Rect *r);
  126.  
  127.     This routine grabs a single frame of video into the current GrafPort, and scales it to 
  128.     fit into the rectangle specified by “r”. “evg” may either be an EasyVideoGrabber that 
  129.     was previously opened by “NewEasyVideoGrabber”, or may be “nil”, in which case one is 
  130.     opened, a frame captured from it, and immediately closed. The disadvantage of passing 
  131.     “nil” is that it is slightly slower, and you cannot determine the video digitizer resolution.
  132.  
  133. void DisposeEasyVideoGrabber(EasyVideoGrabber evg);
  134.  
  135.     When an “EasyVideoGrabber” is no longer needed, it should be disposed with this routine. 
  136.     This will free up the associated hardware for use by other clients.
  137.  
  138.  
  139. Example Of Use
  140.  
  141. The following routine shows the simplest possible use of the EasyVideoGrabber routines. 
  142. The fragment assumes that a GrafPort has been set up to draw into. This code is incorporated 
  143. into a complete Macintosh application, in the sample file, “EasyGrabberTest.c”.
  144.  
  145.  
  146. void ASimpleDigitizingExample(void)
  147.     {
  148.     /*
  149.      * Set the rectangle we'll be drawing into.
  150.      */
  151.     SetRect(&r,0,0,160,120);
  152.  
  153.     /*
  154.      * Let the user click five times
  155.      * and grab a frame each time.
  156.      *
  157.      * This is a somewhat substandard user interface,
  158.      * I am sure you will agree.
  159.      */
  160.     for(i = 0; i < 5; i++)
  161.         {
  162.         /*
  163.          * Wait For A MouseClick
  164.          */
  165.         while(!Button());
  166.         while(Button());
  167.  
  168.         /*
  169.          * Grab a frame into the current GrafPort
  170.          *  allocate and deallocate on the fly.
  171.          */
  172.         gotAFrame = GrabEasyVideoGrabber(nil,&r);
  173.  
  174.         /*
  175.          * If we didn't get a frame, just quit and go home.
  176.          */
  177.         if(!gotAFrame)
  178.             return;
  179.         }
  180.     }
  181.  
  182.  
  183. Conclusion
  184.  
  185.     If you’re writing the Great Macintosh Video Digitizing Application, you’ll probably want 
  186.     to perform the spleen-curdling task of accessing each video digitizer component directly. 
  187.     But if you want to grab some pixels from a digitizer right now, then this little library 
  188.     should be just the ticket.
  189.  
  190.  
  191.